feat: add --category flag to docs search command#603
Conversation
Add a --category flag to `slack docs search` so results can be filtered by category, matching the filters offered by the docs site search modal: guides, reference, changelog, python, javascript, java, slack_cli, slack_github_action, deno_slack_sdk. - internal/api: thread category through DocsSearch, the DocsClient interface, the URL builder (appends &category= when set), and the mock. Add DocsSearchCategories as the shared source of valid values. - cmd/docs: add the --category flag, validate it against DocsSearchCategories (like --output), and pass it to the API for text and json output. For browser output, append &filter= to the search page URL for parity with the site. An empty category preserves the existing search-everything behavior. Docs reference regeneration (slack docgen) happens at release, not here. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #603 +/- ##
==========================================
+ Coverage 71.73% 71.74% +0.01%
==========================================
Files 227 227
Lines 19188 19203 +15
==========================================
+ Hits 13765 13778 +13
- Misses 4213 4215 +2
Partials 1210 1210 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
zimeg
added
enhancement
zimeg
left a comment
zimeg
left a comment
There was a problem hiding this comment.
@lukegalbraithrussell Immense thanks for patient review of a feature we sought 🔍 ✨
I'm leaving approval with LGTM and good testing but am curious to loosen the checks of valid and invalid categories. We can revisit that whenever but are wanting to avoid needing ongoing updates to keep these flag values current 🏁
Most comments are rambles around that point so I apologize for self references of scattered ideas.
|
Thank you for the feedback @zimeg! I loosened up the category checking per your rec! |
| "slack_cli", | ||
| "slack_github_action", | ||
| "deno_slack_sdk", | ||
| "legacy", |
zimeg
changed the title
zimeg
left a comment
zimeg
left a comment
There was a problem hiding this comment.
📚 @lukegalbraithrussell LGTM! The changes most recent are much appreciated and I'm excited to land this with an upcoming release!
I left one comment on error outputs we might explore later but for now let's get this merged? 🚢 💨 🔍
| "passes unknown category through to API": { | ||
| CmdArgs: []string{"search", "test", "--category=bogus"}, | ||
| Setup: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock, cf *shared.ClientFactory) { | ||
| cm.API.On("DocsSearch", mock.Anything, "test", 20, "bogus").Return(&api.DocsSearchResponse{ | ||
| TotalResults: 0, | ||
| Results: []api.DocsSearchItem{}, | ||
| Limit: 20, | ||
| }, nil) | ||
| }, | ||
| ExpectedAsserts: func(t *testing.T, ctx context.Context, cm *shared.ClientsMock) { | ||
| cm.API.AssertCalled(t, "DocsSearch", mock.Anything, "test", 20, "bogus") | ||
| }, | ||
| }, |
There was a problem hiding this comment.
🌟 praise: Thanks for keeping this open as ongoing changes might happen! I find this error meaningful enough to move forward with, but might find revisiting it useful if feedback arrives:
$ slack docs search --category software terminal
🚫 HTTP request failed (http_request_failed)
unexpected status code 400 returned from url https://docs.slack.dev/api/v1/search?query=terminal&limit=20&category=software
2 participants
What
Adds a
--categoryflag toslack docs searchso results can be filtered by category:The docs site search modal lets you filter by category (Guides, Reference, Changelog, the SDK/library docs, etc.), and the
/api/v1/searchendpoint the CLI calls now supports acategoryparam (see slackapi/docs#634). This brings the CLI to parity with both.Categories
The 9 valid categories match the docs search endpoint / site modal:
guides,reference,changelog,python,javascript,java,slack_cli,slack_github_action,deno_slack_sdk', 'legacy(Legacy is being added in this PR)
Changes
internal/api/docs.go— threadcategorythroughDocsSearch, theDocsClientinterface, andbuildDocsSearchURL(appends&category=only when set). AddedDocsSearchCategoriesas the single source of truth for valid values.internal/api/api_mock.go— updated mock signature.cmd/docs/search.go— added the--categoryflag, validated againstDocsSearchCategories(same pattern as--output), passed to the API fortext/jsonoutput. Forbrowseroutput, appends&filter=<category>to the search page URL so the opened page matches.An empty
--category(the default) preserves the current search-everything behavior, so this is backward-compatible.Note
The generated command reference (
docs/reference/commands/slack_docs_search.md) is intentionally not included —slack docgenruns at release time, not per-PR.🤖 Generated with Claude Code